Metadata: YAML
Text: Markdown
Code: knitr or jupyter
Add it all together, and you have beautiful, powerful, and useful outputs!
Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. - Wikipedia
---
title: "ggplot2 demo"
date: "5/22/2021"
format: html
---
## Air Quality
There is a relationship between temperature and the ozone level.
```{r}
#| label: fig-airquality
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) +
geom_point() +
geom_smooth(method = "loess"
)
```“Yet Another Markup Language” or “YAML Ain’t Markup Language”
format: htmlLint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs. - Lint
RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space to see all available options.
Ctrl + space to see the available YAML options . . .
quarto rendersketchyYou can use the HTML reference if needed.
| Markdown Syntax | Output |
|---|---|
|
|
|
|
|
|
|
continues after
|
|
|
| Markdown Syntax | Output |
|---|---|
|
italics and bold |
|
superscript2 / subscript2 |
|
|
|
verbatim code |
| Markdown Syntax | Output |
|---|---|
|
Header 1 |
|
Header 2 |
|
Header 3 |
|
Header 4 |
|
Header 5 |
|
Header 6 |
materials/workshop/02-authoring/markdown-syntax.qmd| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
| Right | Left | Default | Center |
|---|---|---|---|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+===============+===============+====================+
| Bananas | $1.34 | - built-in wrapper |
| | | - bright color |
+---------------+---------------+--------------------+
| Oranges | $2.10 | - cures scurvy |
| | | - tasty |
+---------------+---------------+--------------------+
: Sample grid table.
| Fruit | Price | Advantages |
|---|---|---|
| Bananas | $1.34 |
|
| Oranges | $2.10 |
|
Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:
+---------------+---------------+--------------------+
| Right | Left | Centered |
+==============:+:==============+:==================:+
| Bananas | $1.34 | built-in wrapper |
+---------------+---------------+--------------------+
For headerless tables, the colons go on the top line instead:
+--------------:+:--------------+:------------------:+
| Right | Left | Centered |
+---------------+---------------+--------------------+
Note that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). The RStudio IDE’s Quarto Visual Editor can assist in making these tables.
knitr itself can turn R dataframes into tables with knitr::kable()
A very simple table generator, and it is simple by design. It is not intended to replace any other R packages for making tables. . . .
| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.76 | 3.460 | 20.22 | 1 | 0 | 3 | 1 |
The way you treat code is very different for different contexts
In a teaching scenario like today, I really want to display code
In a business, you may want to have a data-science facing output which displays the source code AND a stakeholder-facing output which hides the code
If you simply want code highlighting, you can use 3x backticks + the language ```r
```r
head(mtcars)
```
If you instead want to see source code and evaluate it, you could use echo: true where echo: false would instead hide the code but still evaluate it.
In some scenarios you want to both execute the code and return the FULL code including backticks, like today where I’m teaching! echo: fenced is a great option for this.
If you want to, you may return purely decorative code which is not executed
The general rule here is that if you want to return code verbatim, you need to have at least N + 1 on the backticks. So for a normal 3x backtick chunk… you’ll need?
Pandoc and therefore Quarto can parse “fenced Div blocks”
::: {.border}
This content can be styled with a border
:::
This content can be styled with a border
This is text with [special]{style="color:red;"} formatting.
This is text with special formatting.
::: div as a HTML <div> but it can also apply in specific situations to content in PDF for example[text]{.class} Spans can be thought of a <span .class>Text</span> but again are a bit more transferable.The following, if specifying a Quarto class can often apply between formats.
:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::
Note
Note that there are five types of callouts, including: note, tip, warning, caution, and important.
Warning
Callouts provide a simple way to attract attention, for example, to this warning.
This is important
Danger, callouts will really improve your writing.
Tip with caption
Caution, under construction
Here is something under construction
:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::
:::{.callout-tip}
## Tip With Caption
This is an example of a callout with a caption.
:::
:::{.callout-caution collapse="true"}
## Expand To Learn About Collapse
This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::
materials/workshop/02-authoring/callout-boxes.qmdmaterials/workshop/02-authoring/callout-pdf.qmd and render it as wellBasic markdown syntax:

Boston Terrier
{fig-align="left"}
{fig-align="right" fig-alt="A photo a Boston Terrier."}
::: {#fig-bostons layout-ncol=2}
{#fig-boston width="250px"}
{#fig-sleep width="250px"}
Two states of Howard
:::
Quarto documents reference from their existing folder/directory.
You can reference sub-directories/folders easily:

But what about going “backwards” i.e. to a parent directory?
This workshop is at "get-started-quarto/materials/"
In code you can use here::here():
The goal of the
herepackage is to enable easy file referencing in project-oriented workflows
[1] "_extensions" "_freeze"
[3] "_quarto.yml" "_site"
[5] "404.qmd" "choose-chinstrap.html"
[7] "docs" "index.qmd"
[9] "LICENSE.md" "materials"
[11] "preview-image-build.R" "preview.png"
[13] "README.md" "workshop-conf-2022.Rproj"
here() always starts at the top-level directory of a RProject
In other situations, like markdown, YAML or the command line/shell/terminal you’ll need to use absolute or relative file paths:
Absolute = BAD: "/Users/thomasmock/get-started-quarto" - who’s computer will this work on?
Better, HTML style relative paths: "../ = up one directory - ../../ = up two directories and so forth - /.. or / = start from root directory
or: "~/get-started-quarto/" where “~” is a shortcut for your home directory (like thomasmock on my computer)
Because Quarto is a command line interface (CLI), there are times you’ll need to use it via the terminal. A great overview of using the command line and navigating files/directories is available via the Data Carpentries or a great interactive tool for understanding commands: https://tldr.ostera.io
| Command | Action |
|---|---|
pwd |
Print name of current working directory |
cd |
Change current working directory |
ls |
List directory contents |
quarto --help |
Return quarto help docs |
mkdir howdy |
Make a new folder/directory called “howdy” |
rm howdy/some-file.qmd | Remove |
a file called some-file.qmd from the “howdy” folder |
tldr toolOpen materials/workshop/02-authoring/figure-layout.qmd
To reference other directories:
Correct the image links:
Use here::here("path/to/content") in code
Use [](~/ProjectDir/path/to/content) in markdown
Use ../../path/to/content in YAML or in Markdown
::: {#fig-bostons layout-nrow=2}
{#fig-boston width="250px"}
{#fig-sleep width="250px"}
{#fig-boston width="250px"}
{#fig-sleep width="250px"}
:::
Two states of Howard, twice
::: {layout-ncol="2"}
{width="250px"}
{width="250px"}
{width="250px"}
{width="250px"}
Two states of Howard, twice
:::
Two states of Howard, twice
Note that the last paragraph in the div block is used as the figure caption.
::: {#fig-dog}
<iframe width="560" height="315" src="https://www.youtube.com/embed/iWR9gwxW-4k"></iframe>
Funny boston terrier videos
:::materials/workshop/02-authoring/figure-layout-2.qmdPandoc supports numbering and formatting footnotes.
Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]
Here is an inline note.1
Notice that the footnote is placed at the bottom of the page in presentations, whereas in a document it would be hoverable or at the end of the document.
Cross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables.
{#fig-elephant}
The presence of the caption (Elephant) and label (#fig-elephant) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:
See @fig-elephant for an illustration.